<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>RF22: RF22 library for Arduino</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />



</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">RF22
   
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.5.1 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="headertitle">
<div class="title"><a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> library for Arduino </div>  </div>
</div>
<div class="contents">
<div class="textblock"><p>This is the Arduino <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> library. It provides an object-oriented interface for sending and receiving data messages with Hope-RF RF22B based radio modules, and compatible chips and modules, including the RFM22B transceiver module such as this one: <a href="http://www.sparkfun.com/products/10153">http://www.sparkfun.com/products/10153</a></p>
<p><a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> also supports some of the features of ZigBee and XBee, (such as mesh routing and automatic route discovery), but with a much less complicated system and less expensive radios.</p>
<p>The Hope-RF (<a href="http://www.hoperf.com">http://www.hoperf.com</a>) RFM22B (<a href="http://www.hoperf.com/rf_fsk/fsk/RFM22B.htm">http://www.hoperf.com/rf_fsk/fsk/RFM22B.htm</a>) is a low-cost ISM transceiver module. It supports FSK, GFSK, OOK over a wide range of frequencies and programmable data rates.</p>
<p>This library provides functions for sending and receiving messages of up to 255 octets on any frequency supported by the RF22B, in a range of predefined data rates and frequency deviations. Frequency can be set with 312Hz precision to any frequency from 240.0MHz to 960.0MHz.</p>
<p>Up to 2 RF22B modules can be connected to an Arduino, permitting the construction of translators and frequency changers, etc.</p>
<p>This library provides classes for</p>
<ul>
<li><a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a>: unaddressed, unreliable messages</li>
<li><a class="el" href="classRF22Datagram.html" title="RF22 subclass for addressed, unreliable messages.">RF22Datagram</a>: addressed, unreliable messages</li>
<li><a class="el" href="classRF22ReliableDatagram.html" title="RF22 subclass for sending addressed, acknowledged, retransmitted datagrams.">RF22ReliableDatagram</a>: addressed, reliable, retransmitted, acknowledged messages.</li>
<li><a class="el" href="classRF22Router.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Router</a>: multi hop delivery from source node to destination node via 0 or more intermediate nodes</li>
<li><a class="el" href="classRF22Mesh.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Mesh</a>: multi hop delivery with automatic route discovery and rediscovery.</li>
</ul>
<p>The following modulation types are suppported with a range of modem configurations for common data rates and frequency deviations:</p>
<ul>
<li>GFSK Gaussian Frequency Shift Keying</li>
<li>FSK Frequency Shift Keying</li>
<li>OOK On-Off Keying</li>
</ul>
<p>Support for other RF22B features such as on-chip temperature measurement, analog-digital converter, transmitter power control etc is also provided.</p>
<p>The latest version of this documentation can be downloaded from <a href="http://www.open.com.au/mikem/arduino/RF22">http://www.open.com.au/mikem/arduino/RF22</a></p>
<p>Example Arduino programs are included to show the main modes of use.</p>
<p>The version of the package that this documentation refers to can be downloaded from <a href="http://www.open.com.au/mikem/arduino/RF22/RF22-1.13.zip">http://www.open.com.au/mikem/arduino/RF22/RF22-1.13.zip</a> You can find the latest version at <a href="http://www.open.com.au/mikem/arduino/RF22">http://www.open.com.au/mikem/arduino/RF22</a></p>
<p>You can also find online help and disussion at <a href="http://groups.google.com/group/rf22-arduino">http://groups.google.com/group/rf22-arduino</a></p>
<p>Tested on Arduino Diecimila and Mega with arduino-0021 on OpenSuSE 11.1 and avr-libc-1.6.1-1.15, cross-avr-binutils-2.19-9.1, cross-avr-gcc-4.1.3_20080612-26.5. With HopeRF RFM22 modules that appear to have RF22B chips on board:</p>
<ul>
<li>Device Type Code = 0x08 (RX/TRX)</li>
<li>Version Code = 0x06 It is known not to work on Diecimila. Dont bother trying.</li>
</ul>
<dl class="user"><dt><b>Packet Format</b></dt><dd></dd></dl>
<p>All messages sent and received by this <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> library must conform to this packet format:</p>
<ul>
<li>8 nibbles (4 octets) PREAMBLE</li>
<li>2 octets SYNC 0x2d, 0xd4</li>
<li>4 octets HEADER: (TO, FROM, ID, FLAGS)</li>
<li>1 octet LENGTH (0 to 255), number of octets in DATA</li>
<li>0 to 255 octets DATA</li>
<li>2 octets CRC computed with CRC16(IBM), computed on HEADER, LENGTH and DATA</li>
</ul>
<p>For technical reasons, the message format is not compatible with the 'HopeRF Radio Transceiver Message Library for Arduino' <a href="http://www.open.com.au/mikem/arduino/HopeRF">http://www.open.com.au/mikem/arduino/HopeRF</a> from the same author. Nor is it compatible with 'Virtual Wire' <a href="http://www.open.com.au/mikem/arduino/VirtualWire.pdf">http://www.open.com.au/mikem/arduino/VirtualWire.pdf</a> also from the same author.</p>
<dl class="user"><dt><b>Connecting RFM-22 to Arduino</b></dt><dd>The physical connection between the RF22B and the Arduino require 3.3V, the 3 x SPI pins (SCK, SDI, SDO), a Slave Select pin and an interrupt pin. Note also that on the RFF22B, it is required to control the TX_ANT and X_ANT pins of the RFM22 in order to enable the antenna connection. The <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> library is configured so that GPIO0 and GPIO1 outputs can control TX_ANT and RX_ANT input pins automatically. You must connect GPIO0 to TX_ANT and GPIO1 to RX_ANT for this automatic antenna switching to occur.</dd></dl>
<p>Connect the RFM-22 to most Arduino's like this (Caution, Arduino Mega has different pins for SPI, see below): </p>
<div class="fragment"><pre class="fragment">                 Arduino      RFM-22B
                 GND----------GND-\ (ground in)
                              SDN-/ (shutdown in)
                 3V3----------VCC   (3.3V in)
 interrupt 0 pin D2-----------NIRQ  (interrupt request out)
          SS pin D10----------NSEL  (chip select in)
         SCK pin D13----------SCK   (SPI clock in)
        MOSI pin D11----------SDI   (SPI Data in)
        MISO pin D12----------SDO   (SPI data out)
                           /--GPIO0 (GPIO0 out to control transmitter antenna TX_ANT
                           \--TX_ANT (TX antenna control in)
                           /--GPIO1 (GPIO1 out to control receiver antenna RX_ANT
                           \--RX_ANT (RX antenna control in)
</pre></div><p> For an Arduino Mega: </p>
<div class="fragment"><pre class="fragment">                 Mega         RFM-22B
                 GND----------GND-\ (ground in)
                              SDN-/ (shutdown in)
                 3V3----------VCC   (3.3V in)
 interrupt 0 pin D2-----------NIRQ  (interrupt request out)
          SS pin D10----------NSEL  (chip select in)
         SCK pin D52----------SCK   (SPI clock in)
        MOSI pin D51----------SDI   (SPI Data in)
        MISO pin D50----------SDO   (SPI data out)
                           /--GPIO0 (GPIO0 out to control transmitter antenna TX_ANT
                           \--TX_ANT (TX antenna control in)
                           /--GPIO1 (GPIO1 out to control receiver antenna RX_ANT
                           \--RX_ANT (RX antenna control in)
</pre></div><p> and you can then use the default constructor RF22(). You can override the default settings for the SS pin and the interrupt in the <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> constructor if you wish to connect the slave select SS to other than pin D10 or the interrupt request to other than pin D2. It is possible to have 2 radios conected to one arduino, provided each radio has its own SS and interrupt line (SCK, SDI and SDO are common to both radios)</p>
<dl class="user"><dt><b>Example programs</b></dt><dd></dd></dl>
<p>The following example programs are provided:</p>
<ul>
<li>rf22_client, rf22_server: Simple client/server pair using <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> class</li>
<li>rf22_datagram_client, rf22_datagram_server: Simple client/server pair using <a class="el" href="classRF22Datagram.html" title="RF22 subclass for addressed, unreliable messages.">RF22Datagram</a> class</li>
<li>rf22_reliable_datagram_client, rf22_reliable_datagram_server: Simple client/server pair using <a class="el" href="classRF22ReliableDatagram.html" title="RF22 subclass for sending addressed, acknowledged, retransmitted datagrams.">RF22ReliableDatagram</a> class</li>
<li>rf22_router_client, rf22_router_server1, rf22_router_server2, rf22_router_server3: Simple <a class="el" href="classRF22Router.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Router</a> network. Requires Arduino Mega.</li>
<li>rf22_mesh_client, rf22_mesh_server1, rf22_mesh_server2, rf22_mesh_server3: Simple <a class="el" href="classRF22Mesh.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Mesh</a> network. Requires Arduino Mega.</li>
<li>rf22_test: Some test code used during development, shows how to call some support functions</li>
<li>rf22_snoop: Dumps in ASCII the contents of all <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> messages received</li>
<li>rf22_specan: Simple spectrum analyser using the RSSI measurements of the <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> (see <a href="specan1.png">Sample output</a> showing a plot from 395.0MHz to 396.0MHz of a signal generator at 395.5MHz amplitude modulated at 100% 1kHz)</li>
</ul>
<dl class="user"><dt><b>Memory</b></dt><dd></dd></dl>
<p>The <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> library requires non-trivial amounts of memory. The sample programs above all compile to about 9 to 14kbytes each, which will fit in the flash proram memory of most Arduinos. However, the RAM requirements are more critical. Most sample programs above will run on Duemilanova, but not on Diecimila. Even on Duemilanova, the RAM requirements are very close to the available memory of 2kbytes. Therefore, you should be vary sparing with RAM use in programs that use the <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a> library on Duemilanova.</p>
<p>The sample <a class="el" href="classRF22Router.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Router</a> and <a class="el" href="classRF22Mesh.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Mesh</a> programs compile to about 14kbytes, and require more RAM than the others. They will not run on Duemilanova or Diecimila, but will run on Arduino Mega.</p>
<p>It is often hard to accurately identify when you are hitting RAM limits on Arduino. The symptoms can include:</p>
<ul>
<li>Mysterious crashes and restarts</li>
<li>Changes in behaviour when seemingly unrelated changes are made (such as adding print() statements)</li>
<li>Hanging</li>
<li>Output from Serial.print() not appearing</li>
</ul>
<p>With an Arduino Mega, with 8 kbytes of SRAM, there is much more RAM headroom for your own elaborate programs. This library is reported to work with Arduino Pro Mini, but that has not been tested by me.</p>
<p>The Arduino UNO is known not to work with <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a>. It appears that something in the Uno is interfering with MISO pin, preventing the RFM initialisation completing. Miso is held at 0 when I would expect the RFM22 to output data on MISO. I suspect it is the U8A USP interface chip (its the only other thing connected to MISO. And if I power the Uno + RFM22 from a battery instead of USB, it works fine. rubinoae reports that installing different firmware in the U8A fixes this problem but that has not been tested by me.</p>
<dl class="user"><dt><b>Installation</b></dt><dd></dd></dl>
<p>Install in the usual way: unzip the distribution zip file to the libraries sub-folder of your sketchbook.</p>
<p>This software is Copyright (C) 2011 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial:</p>
<dl class="user"><dt><b>Open Source Licensing GPL V2</b></dt><dd></dd></dl>
<p>This is the appropriate option if you want to share the source code of your application with everyone you distribute it to, and you also want to give them the right to share who uses it. If you wish to use this software under Open Source Licensing, you must contribute all your source code to the open source community in accordance with the GPL Version 2 when your application is distributed. See <a href="http://www.gnu.org/copyleft/gpl.html">http://www.gnu.org/copyleft/gpl.html</a></p>
<dl class="user"><dt><b>Commercial Licensing</b></dt><dd></dd></dl>
<p>This is the appropriate option if you are creating proprietary applications and you are not prepared to distribute and share the source code of your application. Contact <a href="mailto:info@open.com.au">info@open.com.au</a> for details.</p>
<dl class="user"><dt><b>Revision History</b></dt><dd></dd></dl>
<dl class="version"><dt><b>Version:</b></dt><dd>1.0 Initial release</dd>
<dd>
1.1 Added rf22_snoop and rf22_specan examples</dd>
<dd>
1.2 Changed default modulation to FSK_Rb2_4Fd36 Some internal reorganisation. Added <a class="el" href="classRF22Router.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Router</a> and <a class="el" href="classRF22Mesh.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Mesh</a> classes plus sample programs to support multi-hop and automatic route discovery. </dd>
<dd>
1.3 Removed some unnecessary debug messages. Added virtual doArp and isPhysicalAddress functions to <a class="el" href="classRF22Mesh.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Mesh</a> to support other physical address interpretation schemes (IPV4/IPV6?) </dd>
<dd>
1.4 <a class="el" href="classRF22Router.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Router</a> and <a class="el" href="classRF22Mesh.html" title="RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...">RF22Mesh</a> were inadvertently left out of the distro. </dd>
<dd>
1.5 Improvements contributed by Peter Mousley: Modem config table is now in flash rather than SRAM, saving 400 bytes of SRAM. Allow a user-defined buffer size. Thanks Peter. </dd>
<dd>
1.6 Fixed some minor typos on doc and clarified that this code is for the RF22B. Fixed errors in the definition of the power output constants which were incorrectly set to the values for the <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a>. Reported by Fred Slamen. If you were using a previous version of <a class="el" href="classRF22.html" title="Send and receive unaddressed, unreliable datagrams.">RF22</a>, you probably were not getting the output power you thought. </dd>
<dd>
1.7 Added code to initialise GPIO0 and GPIO1 so they can automatically control the TX_ANT and RX_ANT antenna switching inputs. You must connect GPIO0 to TX_ANT and GPIO1 to RX_ANT for this automatic antenna switching to occur. Updated doc to reflect this new connection requirement </dd>
<dd>
1.8 Changed the name of RF22_ENLBD in RF22_REG_06_INTERRUPT_ENABLE2 to RF22_ENLBDI because it collided with a define of the same name in RF22_REG_07_OPERATING_MODE. RF22_REG_05_INTERRUPT_ENABLE1 enable mask incorrectly used RF22_IFFERROR instead of RF22_ENFFERR. Reported by Steffan Woltjer. </dd>
<dd>
1.9 Fixed typos in RF22_REG_21_CLOCk*. Reported by Steffan Woltjer. </dd>
<dd>
1.10 Fixed a problem where a IFFERR during transmission could cause an infinite loop and a hang. Reported by Raymond Gilbert. </dd>
<dd>
1.11 Fixed an innocuous typo in <a class="el" href="classRF22.html#ae4d40dd937c71fa0094a838297fc315d">RF22::handleInterrupt</a>. Reported by Zhentao.</dd>
<dd>
1.12 Improvements to <a class="el" href="classRF22.html#ac211ed2b29be32088714b4bfa1ebbe4c">RF22::init</a> from Guy Molinari to improve compatibility with some Arduinos. Now reported to be working with official Mega 2560 and Uno. Updated so compiles on Arduino 1.0.</dd>
<dd>
1.13 Announce google support group</dd></dl>
<dl class="author"><dt><b>Author:</b></dt><dd>Mike McCauley (<a href="mailto:mikem@open.com.au">mikem@open.com.au</a>) </dd></dl>
</div></div>


<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.5.1
</small></address>

</body>
</html>
